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j SECTION — DOCUMENT MODIFICATION HISTORY 

Revision 0/07 June 1998 

Created 

Revision 1/16 June 1998 

3: Added interrupt and reset switch info, added screen dimensions and pixel aspect 

ratio 

4: Added info on LisaTest, Office System, MacWorks 

6: Added more memory info, added info about emulator hardware abstraction layer 

9 : Added debugger commands 

12: Created new section #12 FUN STUFF 

13: Changed section # from 12 to 13, added ImageWriter printer info 

Revision 2/18 June 1998 

0: Reformatted, changed "Rev" to "Revision". 

3 : Added more info about the screen . 

6: Changed "assessed" to "accessed", added comments about rolling your own 68k CPU 
emulator, added more info about the MMU registers (e.g. changed the 
TMMURegisters data structure) . 

9: Changed "timers" to "timer" in Set Timing Bucket command, reformatted all 

debugger command descriptions so the abbreviation appears first followed by "/" 
followed by the abbreviation spelled-out, added examples to all debugger 
commands, abbreviated commands are now the only commands accepted by the 
debugger, LP command address parameter is now mandatory, removed the Clear All 
Timing Buckets command since Clear Timing Bucket now does this, changed Reset 
Timing Bucket to also reset all the buckets, for command TM changed "MEMORY 
TRAP" to "MEMORY TRAP - READ" or "MEMORY TRAP - WRITE", added version info 
commands, added PICT and PICTP commands, changed MMU commands so that origin, 
limit, and control components of a MMU register are displayed and set 
separately. 

11: Changed "Windows machine" to "Windows machines", mentioned 2MB memory was also 
supported . 

Revision 3/03 July 1998 

all: Used past tense verbs for all Lisa descriptions. 

6: Improved the logical to physical address diagram, added big/little-endian info. 

7: Mentioned my DTCMacDiskUtility program. 

9: Corrected DM command example, added detailed snapshot file format for the DEM 

command, made file-name arg optional in LOG command, added commands TMV and 

TMP, changed DTM command to show value and pattern info. 
13: Added Wakerly's 68000 book, added Lisa Owner's Guide, improved ImageWriter 

printer info, added Linzmayer's Apple history book. 

Revision 4/05 July 1998 

all: Changed "chapter" to "section", spell checked everything. 

3: Added a picture of a Lisa Office System screen, added listing of the 7 LOS 

tools, now printed on a laser printer instead of my ImageWriter due to the 

screen image which needs a good printer. 
9 : Improved the memory snapshot file format . 
13 : Added info about the Workshop utility programs . 

A FEW IDEAS ABOUT THE DESIGN AND IMPLEMENTATION 

OF A SOFTWARE EMULATOR FOR THE APPLE LISA COMPUTER 

David T. Craig • Revision 4 • 06 July 1998 • 3/39 






j SECTION 1 — ABSTRACT 



This document describes a few ideas I have about the design and implementation of a 
software emulation program that would emulate the Apple Lisa computer. This 
emulator should be strictly software-based and not hardware-based (i.e. no special 
physical devices should exist to make this emulator work) . 



SECTION 2 — ABOUT THE AUTHOR 



David Craig has been involved with the Lisa computer since 1984 when David used a 
Lisa to cross-develop Macintosh applications . David started with a Lisa 2 that was 
upgraded from a Lisa 1 and used version 2 of the Lisa Workshop. David later 
obtained a Lisa 2/10 with Workshop version 3. Since those days David has become 
very interested in the technology behind the Lisa and has tried to collect as much 
Lisa technical information as possible (this collection contains around 350 
documents) . David owns today two Lisas and the majority of the software ever made 
for the Lisa. This includes the Lisa Office System and the Lisa Workshop 
development environment . David also has all the documentation for these programs . 
David can copy whatever a person wants for 10 cents per page plus postage. See the 
REFERENCES section for the details behind the Lisa documents which should be 
important for emulator writers . 

j SECTION 3 — LISA BACKGROUND ~ j 

The Lisa was a micro-computer system sold by Apple Computer between 1983 and 1985. 
The Lisa was one of the first personal computers to sport a graphical user interface 
(GUI) which was controlled by a mouse. The Lisa's claim to fame was that it 
introduced the GUI to the micro industry. The Lisa's user interface was also rather 
radical and was based on a document-centric architecture . This architecture focused 
on documents, not applications. For example, the Lisa user never ran programs, 
instead the user used stationery pads to create documents which when opened (via 
clicking with the mouse) the appropriate Lisa program was run to process the 
document . Apple developed an extensive set of user-oriented software for this 
machine which was very integrated (the Lisa name per Apple represented Local 
Integrated Software Architecture) . There were 7 tools in this suite: 

— Word processor 

— Object-oriented graphics editor 

— Spreadsheet 

— Simple graphics chart maker 

— Project scheduling manager 

— Simple database manager 

— Terminal program 

The Lisa commercially did not fair well but it did cause Apple to produce another 
GUI machine in 1984 named the Macintosh which did much better commercially. This 
GUI was adopted by other companies such as Microsoft and Sun for their desktop-based 
operating systems . 

The Lisa's hardware consisted of a keyboard, a single-button mouse, a 12" B/W 
bitmapped screen, 2 internally connected 860K Twiggy floppy disk drives, 1 
externally connected 5MB ProFile hard disk, a clock chip, and 1MB of main memory 
(1MB was standard, but could be increased to 2MB total with 3rd party memory cards) . 
The later Lisa 2 computer sported a single 400K Sony disk drive and an internal 10MB 
Widget hard disk. The back of the Lisa contained 3 peripheral expansion card slots, 
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o 


LisaWrite 


o 


LisaDraw 


o 


LisaCalc 


o 


LisaGraph 


o 


LisaProject 


o 


LisaList 


o 


LisaTerminal 






1 parallel port, 2 serial ports, and a mouse connector. The expansion slots 
supported special cards (e.g. a 2 port parallel card which was used to communicate 
with ProFile hard disks, a 4 port serial card mainly for Xenix terminal connections, 
an ethernet communication card made by 3Com, and a manufacturing test card used only 
by Apple) . The heart of the Lisa was the Motorola 68000 CPU which ran at 5MHz . 

The Lisa's screen had the following characteristics: 

o 720 pixels wide by 364 pixels high, very clear, no fuzziness 

o Each pixel was represented by a memory bit. There were 262,080 bits, 32,760 
bytes . 

o Each pixel had an aspect ratio of 2/3. This means there were 3 pixels in the 
horizontal direction for every 2 pixels in the vertical direction. A rectangle 30 
pixels wide by 20 tall looked square on the screen. This aspect ratio was chosen to 
make text appear better. 

o There were 90 pixels per inch horizontally, 60 pixels per inch vertically. 

o Black pixel bits were set to 1, white pixel bits were set to 0. 

Also on the back of the Lisa was an Interrupt switch and a Reset switch. The 
interrupt switch when pressed interrupted the Lisa's operation and would activate 
the Lisa's low-level debugger (LisaBug) if installed. The reset switch would reset 
the Lisa completely causing it to re-boot . 

The Lisa also contained on the front a keyboard connector and a soft power-ON/OFF 
switch which when ON glowed. 
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Here are some pictures of the Lisa 1 and Lisa 2 computers . Another Lisa 1 picture 
(from Apple's Lisa design patent) appears on the first page of this paper: 





Lisa 1 Computer 



Lisa 2 Computer 



gl ial 1 1 i 




Lisa 1 Computer 
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Here is a sample screen picture from my Lisa running the last Lisa Office System, 
version 3.0 (a.k.a. Lisa 7/7): 



Desk File/Print 



Type Style Page Layout Arrangement Fill Lines Pen Color 




SECTION 4 — GOALS 



The goals of a Lisa emulator should be : 

o Faithful emulation of the Lisa's hardware and software. 

o Support for Lisa disks . 

o Support for printing. 

o Faithful execution speed. 

Users of the emulator should be able to sit down in front of the emulated Lisa and 
think they were running a real Lisa. For example, when the Lisa emulator user 
starts the Lisa the user would see the boot ROM diagnostic icons that the real Lisa 
displays . The Lisa emulator should be able to boot Lisa disks and run the programs 
on those disks. For example, users should be able to "insert" the LisaTest disk and 
have the Lisa run this diagnostics program. Or the Lisa emulator should be able to 
run the Lisa Office System software . I think that if a Lisa emulator can run the 
LisaTest program and all of this program's tests pass then the emulator will be 
correctly implemented. 

One area of emulation that could be rather neat would be for the Lisa emulator to 
boot and run the Apple MacWorks emulation disk (I recommend MacWorks 3.0, the last 
Apple produced) . Then you would have a host machine emulating the Lisa which would 
be emulating the Macintosh — two emulators in one ! 
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The emulation speed should also be at least as fast as a real Lisa. Given that the 
Lisa's CPU ran at 5MHz I don't think this would be a problem and that the emulator 
may even need to have a user-controlled speed setting for when the emulation was too 
fast. 

I recommend highly that a Lisa emulator writer have access to a working Lisa that is 
running Lisa software . I recommend that the Lisa run the Lisa Office System and the 
Lisa Workshop. Don't use a Lisa running the MacWorks software since you will then 
basically have a Macintosh and not a Lisa. 



SECTION 5 — USER INTERFACE 



The Lisa emulator should appear to the user in either a single window on the screen 
or the whole screen of the emulation machine should be devoted to the Lisa. The 
single window would represent the complete Lisa screen. Within this window the Lisa 
software would create its own windows as the real Lisa did. I recommend the single 
window approach for various reasons : 

o The single window would not interfere with the user's other machine 
activities. If the user decides to do other machine tasks the user could just 
access these tasks as normal (e.g. run a word processor). 

o The bottom of the window could contain additional emulator-specific commands . 
These "commands" which could be icons representing specific functions would be used 
by the Lisa user for special purposes. For example, there could be the following 
icons or functions in this area: 

+ Icon representing the Lisa's power-on/off button. When the Lisa user wanted 
to turn "on" the Lisa the user would press this button and it would "light" just 
like the real button does on the Lisa. When the user wanted to turn "off" the Lisa 
the user would press this button and the Lisa emulator would turn off. 

+ Icon to mount a disk. This icon when pressed would ask the user to select a 
Lisa disk image file for mounting. Once the image file was selected the emulator 
would then inform the Lisa of the new disk and the Lisa would mount the disk as 
normal. To unmount/eject a Lisa disk the user would need to select the disk in the 
Lisa Desktop Manager and use the DM's Eject menu command. 

+ Icons representing all the mounted disks. For example, when the user mounted 
a disk an image of the disk would appear in this area. The icon would contain below 
it the name of the Lisa disk volume (the emulator may need to know where to get this 
volume name from a Lisa disk image — or use a generic name for the disk, e.g. "Disk 
# 2") . 

+ User preferences icon. This icon's function is to allow the user to specify 
certain emulation preferences . These could include things like the speed of the 
emulator. I recommend that the emulator speed be set to something reasonable 
originally but also allow the user to either slow down or speed up the emulation to 
match their speed tastes . I have a feeling that the emulator will for the most part 
be too fast for most users and they will want to slow it down so it acts like a real 
Lisa. 

+ Reset and Interrupt buttons. These should act just like the Lisa's buttons. 
The reset would restart the emulation (not the emulator) . The interrupt should 
either activate LisaBug or cause the Lisa software to display an "interruption has 
occurred" dialog. 
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A second window could also appear in the emulator . This window would be used for 
the Emulator Debugger and would normally not be visible to the user. Advanced 
emulation users or emulator programmers should be able to activate and access this 
window. See the section below for details behind this debugger window. 

j SECTION 6 — EMULATOR SOFTWARE ARCHITECTURE ~ j 

The Lisa emulator program should be divided into three sections : 

1) Emulator kernel — handles all the Lisa hardware emulation. 

2) Emulator debugger — allows a behind-the-scenes emulator view. 

3) Emulator utilities — includes things like emulator preferences. 

The emulator kernel would contain all of the programming necessary for the emulator 
to emulate a Lisa. This programming would include code for the following: 

LOW-LEVEL KERNEL AREAS: 

o 68000 instruction parsing, analysis, execution and timing 

o MMU register reading, writing, and using 

o VIA1 and VIA2 parallel port controllers 

o SCC serial port controller 

o COPS keyboard and mouse controller 

o Screen drawing to both the main and alternate screens 

o Screen Contrast control (emulator may not support this) 

o Speaker Volume and sound tone 

o Floppy and hard disk control 

o Lisa Serial number reading 

o IRQ interrupt and switch handler 

o Reset interrupt and switch handler 

Emulation of the 68000 CPU instruction set is a must. The Lisa emulator should 
contain a complete 68K CPU emulator which is either written by the Lisa emulator 
authors or uses source code for an existing emulator (e.g. I've heard that several 
68000 emulator source packages are available on the internet) . This emulator must 
work closely with the Lisa Emulator Debugger (see the DEBUGGER section) . 

The 68000 is a big-endian CPU so if your host machine is little-endian the emulator 
will need to handle the 68000 ' s 2 and 4 byte register and memory contents 
appropriately . 

A key aspect of this kernel is the complete emulation of the Lisa's hardware 
operations . Also present here should be complete control over all aspects of the 
Lisa including all memory accesses. For example, when a memory access is made the 
68000 instruction analysis section of the emulator should determine if the access is 
for regular memory or memory-mapped I/O memory. If for regular memory then MMU 
logic needs to come into play. If for memory-mapped I/O memory then the appropriate 
hardware action should take place (e.g. reading the Lisa's speaker volume setting). 

Emulator writers must also have a working Lisa that runs the Lisa OS, not other OSs 
such as MacWorks . The reasons for this are so the emulator writers can first see 
exactly how a real Lisa looks while it is running and can peek at the internal 
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operations via techniques such object file disassemblies, LisaBug disassemblies and 
MMU register dumps . 

Emulating the Lisa mouse may be a problem. I recommend that the emulator not use 
the host machine ' s mouse pointer bitmap for the Lisa mouse . Instead, the emulator 
should track the host machine mouse and then draw the Lisa mouse image on the Lisa 
screen as appropriate . This would require the emulator to handle the Lisa mouse ' s 
low-level software implementation and data structures . The Lisa boot ROM has a 
great listing of the mouse routines which I believe are the only mouse routines 
present in the Lisa (i.e. the Lisa hardware library (residing in Lisa file 
SYSTEM. LLD) does not have its own mouse routines but uses the ROM mouse routines) . 

For memory handling I recommend that there exist several memory-based data 
structures which represent the Lisa ' s memory : 

o 68000 CPU registers 

o Main memory (1MB or 2MB) 

o Boot ROM (16KB) 

o MMU register set 

o Memory-mapped I/O 

68000 CPU registers should be supported with the following data structure (written 
as a Pascal record, see a 68000 book for the details) : 



T68000Registers = RECORD 



D 

A 

SS 

PC 

STATUS 



7] of longint; 
7] of longint; 



array [0 
array [0 
longint ; 
longint ; 
: packed record 

trace 

bl4 

supervisor 

bl2 

bll 

inter r up t _ma s k 

b7 

b6 

b5 

extend 

negative 

zero 

overflow 

carry 



{ data registers } 

{ address registers (A7 = user stack ptr) } 

{ supervisor mode stack pointer } 

{ program counter (0-FFFFFF) } 



boolean; 

boolean; 

boolean; 

boolean; 

boolean; 

0..7; 

boolean; 

boolean; 

boolean; 

boolean; 

boolean; 

boolean; 

boolean; 

boolean; 



end; 



END; 



Note that only the low 3 bytes of the PC are interpreted by the Lisa since the 68000 
only supported 16MB of memory. The high byte is ignored. 

Main memory emulation support should consist of a single 1MB or 2MB memory data 
structure that is byte-addressable. Note that the Lisa's screen memory was just 
part of the main machine memory. There was no special memory for the screen. 
Screen memory occupied 32KB. There can also be a secondary screen (called the 
alternate console) which also resided in the main memory. If the emulator host 
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machine cannot accommodate 1MB (or 2MB) of real memory then this memory could be 
handled in a virtual fashion by the emulator . 

Boot ROM memory should consist of a 16KB memory data structure that should contain a 
copy of this ROM and be read-only (the Lisa MMU may already protect this section of 
memory, but I recommend that the emulator monitor this area for writes just in 
case) . 

The Lisa's memory organization was based on a segmented architecture which contained 
a physical memory and hardware (called the MMU) that managed all accesses to the 
physical memory. The Memory Management Unit (MMU) hardware's purpose was to map 
logical memory addresses to physical memory addresses. As far as Lisa applications 
were concerned all of their addresses were logical and could span 16MBs even though 
the Lisa's physical memory was much smaller than 16MBs. The MMU consisted of a set 
of registers that determined the logical-to-physical mapping. The Lisa's boot ROM 
and OS maintained the contents of the MMU registers . See the Lisa hardware manual 
for detailed MMU information. 

Here ' s an overview of the MMU registers and how they were used to map logical 
addresses to physical addresses. MMU registers should be supported by the following 
data structure which represents 4 sets of MMU registers with each set consisting of 
128 24-bit registers: 



TMMURegisters = array 

RECORD 

segment_origin : 
segment_limit : 
segment_control 

END; 



[0. .3,0. .127] of 

12 bits { page physical start address (512 byte page-based) } 
8 bits { page physical size } 
4 bites { page access control } 



There were 4 sets of MMU registers to support fast context switching between Lisa 
software processes. 

A logical address contained 24 bits with a range of $000000 to $FFFFFF (0 to 16MB- 
1) . A logical address was composed of 3 components (as far as the Lisa's hardware 
was concerned, the Lisa programmer saw only logical linear addresses) , "$" 
represents a hexadecimal number: 



o Segment number : 

o Logical block number : 

o Logical displacement : 



Bits 23-17 Width 7 Values 0-127/$7F 
Bits 16-9 Width 8 Values 0-255/$FF 
Bits 8-0 Width 9 Values 0-511/$lFF 
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Here's a diagram of how 24 bit wide logical addresses were converted by the MMU into 
21 bit wide physical addresses (the numbers outside of a box represent the number of 
bits in the closest data path) : 

LOGICAL ADDRESS (24 BITS) 

+ + + + 

| 23 SEGMENT 17 | 16 LOGICAL BLOCK 9 | 8 LOGICAL DISPLACEMENT | 

+ + + + 

17 |8 

| + + v 

| | 128 MMU | + + 

+ — >| REGISTERS | >| ADDER | 

| | 12 + + 

+ + | 12 

v 

+ + — 

| 20 PHYSICAL BLOCK 9 | 8 

+ + 

PHYSICAL ADDRESS (21 BITS) 



PHYSICAL DISPLACEMENT 



+ 

I 
+ 



The segment origin register (12 bits wide) contained the physical memory origin of 
the memory segment which was always on a 512 byte memory boundary. The logical 
address's segment value (upper 7 bits) was used as an index into the appropriate MMU 
origin register. The segment limit register (12 bits wide) contained both the 
segment size in terms of 512-byte pages (8 bits wide) and access control bits (4 
bits wide) for the segment. The control bits determined what general area of memory 
was being accessed (main memory, I/O memory, or special I/O memory) . The control 
bits also determined how the memory was used (read-only or as a stack) . 

If a memory-mapped I/O access is to a part of I/O memory that the emulator does not 
know about then the emulator should alert the user that an internal problem was 
found (the emulator debugger should come into play here) . The emulator writer 
should then be notified and determine what is going on. In general, the emulator's 
memory access should always be to memory locations that the emulator is completely 
cognizant about . I recommend that there exist in the emulator a programming module 
called the Lisa Hardware Abstraction Layer. This module's purpose is to handle all 
hardware access to the emulator's host machine. For example, there should exist a 
routine here that reads the host machine's keyboard. When the emulator detects that 
the Lisa is trying to read the Lisa keyboard this module ' s keyboard routine would be 
called. Having this module is important since it segregates all host machine 
hardware access to a single area in the emulator which if the emulator is moved to 
another machine then only one area should need changing. 
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The Lisa's memory is accessed using the following physical memory map which shows 
what regions of physical memory hold what information (x in an address means don't- 
care, see the Lisa hardware manual for complete details) : 



Main RAM 

Main RAM 

Boot ROM 

I/O space 

Expansion slot 1 
Expansion slot 2 
Expansion slot 3 
Floppy disk control 
Serial port control 
Parallel port control 
Keyboard/Mouse control 
CPU board control 
(unused) 

Video address latch 
Memory error address latch 
Status register 



0-1FFFFF (1MB) 
0-2FFFFF (2MB) 
FExxxx (16KB) 
FCxxxx 

FC0000-FC3FFF 

FC4000-FC7FFF 

FC8000-FCBFFF 

FCC001-FCCF77 

FCD000-FCD3FF 

FCD800-FCDBFF 

FCDCOO-FCDFFF 

FCE000-FCE01E 

FCE01F-FCE7FF 

FCE8xx 

FCFOxx 

FCF8xx 



Note: The Lisa also maintained a 128 byte chunk of memory whose contents were 
backed up by the Lisa's battery when the Lisa was powered-off. This memory was 
called Parameter Memory. I'm note sure where this memory resided in the above 
memory diagram but suspect it was in the I/O space. 

Correct timing for the CPU and its instructions may be important for the emulator. 
For example, when the Lisa wants to read the Lisa's serial number (which is stored 
in the Lisa Video State ROM chip) access to the bits of this number occur at 
specific times only. It seems to me that accurate timing could be very difficult to 
achieve . 

Note: Since the Video State ROM is not something that an emulator can access you may 
want to simulate this chip by having your code report whatever information the Lisa 
needs . For the serial number I recommend that you use a real serial number which I 
can provide from my Lisa. 

All of the low-level controls for floppy and hard disks should be supported. I 
recommend supporting the Sony 400K floppy, the ProFile 5MB hard disk, and the Widget 
10MB hard disk. I recommend against supporting the Twiggy 860K floppies that 
shipped with the Lisa 1 since I'm not sure if the last Lisa Office System (version 
3.0 — Lisa 7/7) supports Twiggies . This support in the emulator could be fairly 
tricky since the controls for disks seem complicated in the Lisa hardware manual . 
Also, support for the ProFile and Widget needs to follow a specific communications 
protocol (I have the docs detailing this protocol) . Support for the floppy could be 
achieved using either of two strategies . You could emulate the really low-level 
hardware stuff such as the 6504 chip or you could just intercept calls to the floppy 
and use your host machine's OS to perform file-based disk I/O. 

The Lisa can support two virtual terminals. In normal use (e.g. typical users using 
the Lisa Office System) there is only one screen, called the main screen. This is 
just a chunk of memory that is treated as a single bitmap by the Lisa's drawing code 
QuickDraw. But when the LisaBug debugger is installed there exists a second screen 
called the alternate screen. It is just another bitmap in memory. All LisaBug 
output is to this screen and it supports only text output even though it is at the 
lowest levels a bitmap. 
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HIGH-LEVEL KERNEL AREAS: 

o Printing 

The emulator utilities would cover the following: 

o Emulator window handling (e.g. moving) 

o Emulator disk image mounting, unmounting, and creating 

o Emulator preferences 

o Emulator access to Lisa disks 

o Emulator debugger 

o Emulator logging 

Emulator access to Lisa disks may be extended from just providing the bare block- 
level accesses to file-level access. To achieve this the emulator would need to 
know the format of Lisa disks. This information, some of which I have, is fairly- 
complicated since there were 3 different file formats supported by the Lisa over 
time . These file systems ranged from a flat-file system to a hierarchical system 
with various format changes in each main file system version. There was also a very 
old file system supported by the Lisa which ran under the Lisa Monitor OS . This was 
a UCSD-P System-based file system whose directory structure is specified in the Lisa 
Desktop Library interfaces . Though this FS is the oldest several of Apple ' s Lisa 
programs used it (e.g. LisaTest and MacWorks) . I recommend that this feature allow 
the user to at least copy files from a mounted Lisa disk to the user's host machine 
FS. 

Emulator logging seems like a very useful feature for the emulator writer. This 
feature would log all important events that occur within the emulator. This logging 
should occur to a file in the host machine's file system. 



SECTION 7 — LISA DISK IMAGES 



The Lisa emulator should support the mounting, unmounting, and creation of disks 
just like the real Lisa does . See the USER INTERFACE section for a description of 
how the emulator user would deal with disks . 

I recommend that no real Lisa disks be used with the emulator. Instead I recommend 
virtual disks be used. Specifically, I would use disk image files. For example, 
the Apple Macintosh computer can read and write Lisa disks at the block level using 
various Macintosh utility programs (e.g. Disk Copy from Apple Computer) . These 
utilities can read a Lisa disk and can then create a file representing this disk on 
a Macintosh disk. The emulator should use these disks since they are platform 
neutral (e.g. these images are just files which non-Macintosh machines such as the 
PC can easily handle) . 

I recommend that the disk image files be created by a program that the emulator 
writer has complete programming control over. For example, I have a Macintosh disk 
utility program (named DTCMacDiskUtility) which can read and write its own image 
files and can read and write to Lisa floppy disks . The format of these files is 
documented and I have complete control over this program so that if bugs are 
detected or new features are needed I can resolve these . 

The disk image files should support the Lisa 400K Sony floppies and the Apple 
ProFile 5MB or Apple Widget 10MB hard disks. 
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David Craig has disk image copies of all of the Lisa version 3 software which 
includes the Lisa Office System and the Lisa Workshop. David also has other Lisa 
disks with items like the Lisa Art Department (a clipart set) and the Lisa ToolKit 
development libraries and sources . 



SECTION 8 — PRINTING EMULATION 



The emulator should also support printing. 

Since the Lisa supported the Apple ImageWriter dot matrix printer and the Apple 
Daisy Wheel printer the emulator should support at least one of these . I recommend 
supporting the ImageWriter printer. To support these printers you will need to know 
the command sets for each printer (I have the reference manuals for these printers 
which contain this information) . For the ImageWriter you would also need to know 
its character bitmaps (the reference manual contains these) . 

The emulator should print to whatever printer is attached to it using whatever 
printer driver is normally used. For example, the emulator could print to a laser 
printer yet the emulator would be simulating the ImageWriter. The output should 
look exactly like the original printer's output. For example, since the ImageWriter 
could print at a resolution of around 144 dpi the output from the emulator should 
look like 144 dpi printing (for laser printers that print at 300 or higher dpi today 
the emulator writer would need to scale the emulator printout to fit this dpi) . 



SECTION 9 — DEBUGGER 



The Lisa emulator should support a powerful built-in debugger. The purpose of this 
debugger is to give emulator writers a tool for analyzing and controlling emulator 
operations . Without this debugger creating an emulator would be a very difficult 
task. For example, this debugger would support access to any of the memory used by 
the emulator for emulation data structures such as the 1MB of RAM that the Lisa 
uses, the 68000 CPU registers, and the Lisa MMU registers. 

I recommend that this debugger be a separate window that the user can display at any 
time. Display of this window could be through a special keypress (e.g. CONTROL- 
SHIFT-D) . The user should interact with this debugger via a command-line interface 
since this type of control is fairly easy to implement, can easily be extended, and 
fits the psyche of many programmers . This window should mostly contain a simple 
text I/O area that covers the majority of the window. You could also have a small 
area containing all of the 68000 CPU registers and maybe some other stuff specific 
to the Lisa (e.g. the Lisa MMU domain value) . This area could exist on the left 
side of the debugger window in the same way that Apple ' s MacsBug debugger window 
appears. I recommend against having a specific area for debugger commands, these 
should co-exist with the standard text I/O area. 

Debugger activation should always display the emulator and debugger version numbers . 
This information could be useful when a person examines a debugger log and needs to 
know which version of the emulator or debugger made the debugger log. 

Activation of the debugger should include a message from the emulator describing the 
reason for the activation. There would need to exist a message passing capability 
between the emulator and the debugger (in the Macintosh world there is such a 
capability called the DebugStr system call) . After the activation message there 
should appear a dump of the Lisa's 68000 registers (see the D68 debugger command for 
a sample register dump) . Activation messages should include the following: 
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USER ENTRY 

This appears when the user activates the debugger. 

MEMORY ACCESS VIOLATION 

This appears when there is an access to memory which the emulator does not support . 

68000 EXCEPTION 

This appears when there is a 68000 CPU opcode error. For example, ADDRESS ERROR or 
ILLEGAL INSTRUCTION (see the 68000 manual or page 8-3 of the LisaBug documentation 
for a complete list) . I'm not sure if these exceptions should be handled by the 
emulator since there may be another way to handle these (e.g., the emulator should 
pass these on to the Lisa exception handlers which will do whatever the Lisa 
normally does) . 

Activation should also display the message "Type EXIT to return to the Emulator" 
since this message could really help non-technical users who inadvertently enter the 
debugger . 

The debugger should support the following types of commands : 

o On-line help 

o Version information 

o Execution control 

o 68000 CPU register and code access 

o Memory access 

o MMU register access 

o Code tracing (with single stepping) 

o Code timing 

o Memory access trapping 

o Logging and memory dumping 

o Disk block dumping 

The command set for the debugger could either be based on LisaBug 's command set or 
it could be completely different . I recommend that the command set be different 
than LisaBug 's commands so that the commands can be more understandable. There 
should also exist on-line command help so that the user need not have to read a 
manual to understand the commands . I also recommend that if an invalid command is 
entered by the user that the debugger tell the user the command is invalid and tell 
the user how to access the on-line command help. 

Additional non-LisaBug commands could also be supported for special purposes . For 
example, writing all of the emulator memory data structures to a snapshot file which 
could be read into the emulator at a later time for analysis . 

All debugger window output should be stored in a text file . The default text file 
is named "Lisa Emul Debug YYYYMMDD HHMMSS" where YYYYMMDD is the current date and 
HHMMSS is the current time in 24-hour format. This file is created when the 
debugger first starts and is closed when the emulator quits . 

Debugger commands which can generate lots of screen output should be pausable and 
stoppable by the user. I recommend using the SPACE key as the pause and resume key 
and the ESCAPE key or a control (or Apple) key press in conjunction with a standard 
key such as Q. 
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Each debugger command name has a full name and an abbreviated name . Only the 
abbreviated names are understood by the debugger. Command character case should be 
immaterial. Command names may be followed by parameters (character case here is 
also immaterial) . Optional parameters are enclosed in {}. All command value 
parameters are in hexadecimal (e.g. 10 means decimal 16, A means decimal 10) . 

I recommend the following Lisa Emulator Debugger commands : 

ON-LINE HELP COMMANDS 

o ? / HELP {command} 

Displays detailed on-line help information for the specified command abbreviation. 
If command is not present then lists all of the commands showing a single line of 
help for each command. 

Example : ? V 

Display version information for both the Lisa emulator and the debugger. 

VERSION INFORMATION COMMANDS 

O V / VERSION 

Displays version information for both the Lisa emulator and the debugger. Version 
information has the format A.BC.DE where A is the main version, BC is the revision 
level (changes to functionally have been made), and DE is the bug fix level. There 
should also be a date associated with each version number (dates should have a 
universal format such as YYYY-MM-DD, e.g. 1969-07-20 represents 20 July 1969) . 

Example : V 

Lisa Emulator Version 0.00.00 [1969-07-20] 
Debugger Version 0.00.00 [1969-07-18] 

EXECUTION CONTROL COMMANDS 

o EXIT (or BYE) 

Example : EXIT 

Returns to the emulator. 

o G / GO {address} 

Starts execution of 68000 code at the address. If address is not present then 
execute at the current 68000 program counter. 

68000 CPU REGISTER AND CODE ACCESS COMMANDS 
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o D68 / DUMP 68000 REGISTERS 

Displays the 68000 CPU registers. 



Example : 

PC=XXXXXXXX 

D =xxxxxxxx 
D 4 =xxxxxxxx 
A0 =xxxxxxxx 
A4 =xxxxxxxx 



D68 

SR=xxxxxxxx 
D 1 =xxxxxxxx 
D 5 =xxxxxxxx 
Al =xxxxxxxx 
A5 =xxxxxxxx 



US=xxxxxxxx 
D 2 =xxxxxxxx 
D 6=xxxxxxxx 
A2 =xxxxxxxx 
A 6 =xxxxxxxx 



S S =xxxxxxxx 
D 3 =xxxxxxxx 
D 7 =xxxxxxxx 
A3 =xxxxxxxx 
A7 =xxxxxxxx 



DO=x 



Note: SR is the Status Register, US is the User Stack pointer, SS is the Supervisor 
Stack pointer, and DO is the Lisa MMU domain (I'm including this here since it is 
useful to know about) . 

o S68 / SET 68000 REGISTER register value 

Sets the 68000 CPU register to the specified value. Address registers are specified 
as A0 to A7, data registers as DO to D7, program counter as PC, status register as 
SR, and the supervisor stack pointer as SS (A7 is the user stack pointer which can 
also be specified as US) . 

Example: S68 A0 12345678 

Sets 68000 register A0 to 12345678. 

o D / DISASSEMBLE {start-addr} {end-addr} 

Disassembles 68000 code starting from address start-addr to end-addr. If only 1 
address is present then disassemble 20 instructions from start-addr. If no 
addresses are present then disassemble 20 instructions starting at the instruction 
just after the last disassembled instruction. The disassembled output contains the 
address, hex opcodes, ASCII for the opcodes, and disassembled instructions. Invalid 
opcodes display "???". Note that "$" in front of a number means hexadecimal (this 
is the standard way Motorola assemblers /debuggers show these numbers so I'm doing 
the same here) . 



Example : 


D 100 10D 




00000100: 


4A62 EFF2 


'Rt..' TST.W $EFF2(A7) 


00000104: 


4E56 FFF2 


'W6..' LINK A6,#$FFF2 


00000108: 


3D7C 0009 FFFE 


'C$....' MOVE.W #$0009,$FFFE(A6) 
MEMORY ACCESS COMMANDS 


o DM 


/ DUMP MEMORY {start- 


-addr) {end-addr} 



Displays memory in a standard hex/ascii dump format beginning at start-addr and 
ending at end-addr. If end-addr is not entered then displays 64 bytes. If start- 
addr is not specified then display the next 64 bytes . Each outputted line always 
contains 16 bytes displayed first as hex values then followed by 16 characters 
representing those 16 bytes' ASCII values. ASCII values not in the range $21-$7E 
are printed as ".". The memory can be any area of the Lisa's memory including main 
memory, ROM memory, or I/O memory. 
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Example: DM 10 

000000: 00 01 02 03 04 05 06 07 08 09 0A OB OC OD OE OF . . . .XYZ . . 5rfU. . @ 

o SM / SET MEMORY start-addr values 

Sets main memory starting at start-addr to the values contained in values . 

Example: SM 11223344 

Sets memory starting at address so that address contains 11, address 1 contains 
22, address 2 contains 33, and address 3 contains 44. 

o FM / FIND MEMORY start-addr end-addr pattern 

Finds patterns in memory. The pattern can be any number of bytes (but it must 
contain an even number of hexadecimal digits) . 

Example: FM 1FFFFF A900 

Searches memory in the range 0-1FFFFF for the word pattern A900. 

o CM / COMPARE MEMORY start-addr end-addr dest-addr 

Compares the bytes in the range start-addr to end-addr against the bytes starting at 
dest-addr. Any mismatches produce the message "Mismatch starting at address x" . A 
complete match produces the message "Equal . " 

Example: CM IFF 500 

Mismatch starting at address 123 (for a mismatch) 

Equal (for a match) 

MMU REGISTER ACCESS COMMANDS 

O DMMUD / DUMP MMU DOMAIN 

Displays the current MMU domain value (range: 0-3) . 

Example : DMMUD 

DOMAIN 

o DMMU / DUMP MMU REGISTERS domain {start-reg} {end-reg} 

Displays the Lisa MMU registers for the domain (0-3) starting at start-reg and 
ending at end-reg with register range being 0-7F . If one register exists then only 
that register's fields are listed. If no registers exist then all registers are 
displayed. If domain is "ALL" then all 4 domain MMU register sets are displayed. 

Example: DMMU 7F 

DOMAIN : MMU REGISTER 7F — Origin xxx Limit xx Control x info 

Note: Info describes the access controls for the segment in language such as "Read- 
Only", "Read-Write", or "Stack". 

A FEW IDEAS ABOUT THE DESIGN AND IMPLEMENTATION 

OF A SOFTWARE EMULATOR FOR THE APPLE LISA COMPUTER 

David T. Craig • Revision 4 • 06 July 1998 • 19/39 






o SMMU / SET MMU REGISTERS domain register origin limit control 

Sets the MMU register values for the specified domain (0-3) . Register must be in 
the range 0-7F . Origin is a 3 nibble value (0-FFF) , limit is a 2 nibble value (00- 
FF) , and control is a single nibble value (0-F) . This command can be a very- 
dangerous command so be super careful here . 

Example: SMMU 2 7F 12A 5F C 

Sets register 7F in domain 2 so that the origin is 12A, the limit is 5F, and the 
control is C. 

o LP / LOGICAL TO PHYSICAL address 

Displays the physical address corresponding to the logical address . Also shows the 
3 components of a logical address from the MMU's perspective. Each component value 
is listed in hexadecimal (e.g. $09), decimal (e.g. 9), and binary (e.g. %0001001) . 
This will be very useful for testing the emulator's MMU handling. 

Example: LP 123456 

LOGICAL ADDRESS = 123456 PHYSICAL ADDRESS = FC379A 
LOGICAL ADDRESS COMPONENTS: 

SEGMENT NUMBER = $09 / 9 / %0001001 

LOGICAL BLOCK NUMBER = $1A / 26 / %00011010 

LOGICAL DISPLACEMENT = $056 / 86 / %001010110 

Note: $123456 has the binary value %000100100011010001010110 . 

CODE TRACING COMMANDS 

O T / TRACE 

Executes the next 68000 instruction and displays the 68000 registers (see command 
D68 for an example of the register dump) . To trace more instructions just press the 
RETURN or ENTER keys. 

Example : T 

O BP / SET BREAK POINT address 

Sets a break point at the address. Up to 100 break points are supported and are 
stored in a table. Duplicate break point addresses are detected and not added to 
the table. When the emulator attempts to execute the instruction at an address that 
resides in the break point table the debugger stops program execution, displays the 
message "BREAK POINT ENCOUNTERED", displays a dump of the 68000 registers, and waits 
for the user to enter a command. 

Example: BP 123456 
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O DBP / DUMP BREAK POINT TABLE 

Dumps all of the defined addresses in the break point address table . 
Example : DBP 
# ADDRESS 



00123456 

1 00005000 



o CBP / CLEAR BREAK POINT { break-point #} 

Clears a break point. If break-point# is not present then clear all the break 
points (it asks you first if this is OK) . Use the DBP command to get the break- 
point# . 

Example: CBP 4 (clears break point # 4) 

CBP (clears all the break points) 

CODE TIMING COMMANDS 

o TB / SET TIMING BUCKET start-addr end-addr 

Sets a timing bucket between addresses start-addr and end-addr. When the emulator 
encounters address start-addr it starts a 1/100 second timer until end-addr is 
reached. Up to 100 timing buckets can be defined. 

Example: TB 100 200 (sets a timing bucket for addresses 100-200) 

O DTB / DUMP TIMING BUCKETS 

Displays all of the defined timing buckets showing their starting address and their 
ending address. 

Example : DTB 

# START END 

00123400 001234FF 

O CTB / CLEAR TIMING BUCKET {bucket #} 

Clears the timing bucket specified by bucket bucket#. If bucket# is not present 
then clears all the timing buckets (it asks you first if this is OK) . Use the DTB 
command to get bucket# . 

Example : CTB 2 

o RTB / RESET TIMING BUCKET {bucket#start} {bucket #-end} 

Resets the count and the elapsed time for a range of timing buckets. If only 1 
timing bucket is specified then resets only that bucket's information. If no 
buckets are specified it resets all the buckets (it asks you first if this is OK) . 
Use the DTB command to get bucket# . 
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Example: RTB 6 (resets bucket # 6) 

RTB 6 10 (resets buckets # 6 to 10) 

RTB (resets all the buckets) 

O DTBR / DUMP TIMING BUCKET REPORT 

Displays a report detailing the time and number of times a timing bucket was 
entered. Time is in 1/100 second increments. 

Example : DTBR 

# START END COUNT TIME 

00123400 001234FF 21 125 

MEMORY ACCESS TRAPPING COMMANDS 

o TM / TRAP MEMORY access-mode start-addr {end-addr} 

Traps a memory access to any address within the address range. If end-addr is not 
present then traps only accesses to the byte at addr-start. Access-mode is either 
"R" for read-access, "W" for write-access, or "B" for both read- or write-access . 
When the emulator encounters an access to this address range it activates the 
debugger, displays the message "MEMORY TRAP - READ" or "MEMORY TRAP - WRITE" 
followed by the memory address which was trapped. Up to 100 memory traps may be 
defined. This is a very powerful command which emulator designers will use a lot. 

Example: TM R FC0000 FC00FF 

Traps any memory reads to addresses in the range FC0000-FC00FF . 

O TMV / TRAP MEMORY VALUE 

access-mode start-addr end-addr value 

Traps accesses to the address range but only for the specified value parameter. See 
the TM command for a general discussion of memory trapping. The number of hex digits 
in value determines whether the access is byte, word, or long based. 

Example: TMV W 100 IFF AAAA 

Traps any write of the word value $AAAA to address range 100-1FF. 

O TMP / TRAP MEMORY PATTERN 

access-mode start-addr end-addr pattern 

Traps accesses to the address range but only for the specific pattern parameter. 
See the TMV command for general information. The pattern is bit-based and specifies 
the bit pattern that triggers the trap. The pattern must be 8 bits long for byte 
trapping, or 16 bits long for word trapping, or 32 bits long for long trapping. A 
don't-care bit value of "x" may be specified. 

Example: TMP W 100 IFF 00001111 (traps if byte $0F written) 

TMP W 100 IFF Oxxxxxx (traps if byte with high bit = 0) 
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O DTM / DUMP TRAP MEMORY TABLE 

Displays all of the memory defined traps . See the TM, TMV, and TMP commands . 
Example : DTM 
# START END MODE VALUE PATTERN 

00FC0000 00FC00FF R FFFF 

1 00000100 000001FF W Oxxxxxxx 

O CTM / CLEAR TRAP MEMORY {trap#} 

Clears the memory trap specified by trap#. If trap# is not present then clears all 
the memory traps (it asks you first if this is OK) . Use the DTM command to 
determine the trap# . 

Example: CTM 23 (clears memory trap # 23) 

CTM (clears all the memory traps) 

LOGGING AND MEMORY DUMPING COMMANDS 

o LOG / LOG {file-name} 

Starts logging all debugger information to the text file named file-name. The 
current log file is first closed. If file-name argument is not entered then closes 
the current log file. If the file name contains spaces then delimit the name in 
either double (") or single (') quotes. 

Example : LOG f oobar . text 

Creates a new log file named "foobar .text" . 

o DEM / DUMP EMULATOR MEMORY file-name 

Dumps all the emulator's Lisa memory data structures to the binary file named file- 
name . This is a snapshot facility that can be very useful for debugging an emulator 
that has gone nuts. This file should contain the 68000 registers, the Lisa's main 
memory, the Lisa's MMU registers, the I/O registers and any other memory that this 
emulator maintains for the Lisa environment. If the file name contains spaces then 
delimit the name with either double (") or single (') quotes (e.g. "My Tag File" or 
'My Tag File' ) . 

Note : I recommend that this binary file contain a short header that indicates this 
file is a Lisa Emulator memory snapshot . Following this header should appear tagged 
data objects . These objects have a short header which specifies the type of data 
object it is (e.g. 68000 registers) and the size of the object (e.g. 100 bytes). 
Having a tagged structure simplifies the creation and modification of these files in 
case changes need to be made the changes (e.g. a new object) should be upwardly 
compatible. Tagged object data files have been used successfully in the past, e.g. 
the TIFF (Tagged Image File Format) which I believe was developed by Microsoft and 
Aldus to store image data in a machine-neutral fashion. 
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I recommend the following detailed tagged object file format : 

+ + 

| HEADER OBJECT | 

+ + 

| OBJECT 1 | 

+ + 

I ••• I 

+ + 

| OBJECT N | 

+ + 

| FOOTER OBJECT | 
+ + 

The HEADER OBJECT must be the first object in the file. The FOOTER OBJECT must be 
the last object in the file. The other objects may be in any order. I recommend 
the following tags for this file ("*" should be used in the tag name so that the tag 
is always 16 bytes long, I also recommend that each tag name contain only human- 
readable characters) : 



Object 

Header 

Footer 

68000 

MMU 

Main Mem 

Main Mem 

Screen Main 

Screen Alt 

ROM Mem 

I/O Space 



Tag 

LisaEmulSnapshot 

LisaEmulFinis*** 

MC68000********* 

LisaMMU********* 

LisaMainMemorylM 

LisaMainMemory2M 

LisaScreenMain** 

LisaScreenAlt*** 

LisaBootROM***** 

LisalOMemory**** 



Contents 

Header object (always first) 

Footer object (always last) 

68000 registers 

Lisa MMU registers 

Lisa main memory — 1 MB 

Lisa main memory — 2 MB 

Address of Lisa's main screen 

Address of Lisa's alternate screen 

Lisa boot ROM image (16KB) 

Lisa I/O memory 



Note : A file should normally contain only one Main Mem object corresponding to the 
size of main memory. The Screen Main and Screen Alt tags exist so that it is easy 
to access the main and alternate (if present) screen areas in the Lisa Mem object 
for debugging or whatever purpose . 
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A tagged object should have the following general format : 

+ + 

| OBJECT TAG (16 BYTES) | 
+ + 

| OBJECT DATA BYTE LENGTH L ( 4 BYTES) | 
+ + 

| OBJECT DATA CHECKSUM ( 4 BYTES) | 
+ + 

| FLAGS [1] ( 4 BYTES) | 
+ + 

| DATA ENCRYPTION METHOD [2] (2 BYTES) | 
+ + 

| RESERVED [3] (12 BYTES) | 
+ + 

| OBJECT HEADER CHECKSUM [4] (4 BYTES) | 
+ + 

| OBJECT DATA ( L BYTES) | 
+ + 

Note [1] : The FLAGS field can hold up to 32 flags. None are currently defined so 
this field should contain just the value 0. Future flag use could encompass flags 
such as a read-only flag or a encryption flag. 

Note [2] : The RESERVED field should contain 0s. 

Note [3] : The DATA ENCRYPTION METHOD determines if the object data is encrypted. 
If this value contains then no encryption is used (i.e. plain-text data) . Other 
values could be defined for different types of encryption. 

Note [4] : The OBJECT HEADER CHECKSUM should be a checksum of all of the object 
fields above this field. I recommend that the checksum be simple to compute yet 
contains radically different results for similar data. I have had lots of success 
with the following simple checksum algorithm which checksums a set of 4 byte long 
values (to checksum a set of bytes you would need to change this algorithm from long 
accesses to byte accesses) : 

1. Init checksum to $6E8E8A00 (%01101110100011101000101000000000) 

2 . For each long value do 

a) Exclusive-OR the checksum and the value 

b) Rotate left 31 bits the value from step a) 

c) The value from step b) is the current checksum 

3 . Return the final checksum value 

For example, this algorithm for the single long produces a checksum value of 
$37474500. For the long value 1 the checksum is $B7474500. 
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An implementation in Apple MPW Pascal of this algorithm is : 

{ return a checksum for a list of longints based on an inputted checksum: 

_longs = pointer to first long 

_count = number of longs 

_checksum = input and output checksum value } 

procedure CalcChecksum (_longs : Ptr; _count : integer; var _checksum: longint) ; 

type tLongPtr = A longint; 

var i: integer; 
1 : longint ; 

begin 
i := 0; 

while _count > do begin 

1 := tLongPtr(ord4(_longs)+(i*4)) A ; 
_checksum := BROTL ( BXOR (_checksum, 1) , 31 ) ; 
i := i + 1; 
_count := _count - 1; 
end; 
end; 

The HEADER OBJECT should contain the following data fields : 

+ + + + 

| BYTE ORDER [1] I 2 BYTES | "LL" for Little-Endian, "BB" for Big-Endian | 

+ + + + 

| CREATION DATE | 10 BYTES | "YYYY-MM-DD" | 

+ + + + 

| CREATION TIME | 8 BYTES | "HH:MM:SS" in 24-hour time | 

+ + + + 

| CREATION PROGRAM | 64 BYTES | Name of program that created this file | 

+ + + + 

| PROGRAM VERSION | 64 BYTES | Version number and compile date of program | 

+ + + + 

| ACCESS PASSWORD [2] | 16 BYTES | Access password I 

+ + + + 

| COMMENTS [3] | 256 BYTES | Any comments the program wants here | 

+ + + + 

| RESERVED | 92 BYTES | Reserved for future use — fill with 0s | 
+ + + + 

Note [1] : The BYTE ORDER field is very important since it specifies how multi-byte 
integral values are physically stored in the file. If your emulator's host machine 
is running a Big-Endian CPU such as a 68000 family chip then most likely BYTE ORDER 
will contain "BB" . If your host CPU is an Intel chip then most likely the BYTE 
ORDER will be ""LL". But this ordering as determined by the BYTE ORDER field _only_ 
applies to the tagged object file and the computer that creates this file can use 
whatever order it wants as long as it defines BYTE ORDER appropriately. Also note 
that BYTE ORDER applies to _all_ of the objects in the file and not just the header 
object. Also, the byte order does not apply to the contents of the data field in an 
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object, this field's contents are explicity defined by the object containing this 
data. 

Note [2] : The ACCESS PASSWORD field contains a password string (with up to 16 
characters) that the creator has assigned to this file for access control. The 
password itself should be encrypted in some fashion so that viewing a hex dump of 
this file won't show the password as plain-text. I recommend a simple password 
encryption scheme such as exclusive-ORing each byte with a string of known bytes . 
If this field contains all Os then no password exists. I also recommend that this 
password not be case-sensitive (why? I hate case-sensitive passwords) . This is not 
a Pascal string. 

Note [3] : The COMMENTS field should contain a Pascal-style string. This means the 
first byte of the string contains the string's length in characters. The rest of 
the string contains the actual string characters. A 256 byte Pascal string can 
therefore hold 255 characters maximum which should provide plenty of space for a 
comment . 

Example : DEM f oobar . memory 

Dumps emulator memory to a file named "f oobar .memory" . 

o LEM / LOAD EMULATOR MEMORY file-name 

Loads a saved emulator dump file . This replaces all of the active emulator data 
structures, displays the 68000 registers, and then waits for you to type a debugger 
command. You can then examine these structures with debugger commands and then 
continue execution. 

Example : LEM f oobar . memory 

PICT / WRITE SCREEN PICTURE 

Creates a picture file of the Lisa emulator screen to files named "Lisa Emul Picture 
NNNN. suffix" where NNNN is a number and suffix is a suffix (e.g. "Lisa Emul Picture 
0001. pict") . The picture file could be a standard file for the host machine. For 
example, if the host is a Macintosh then produce standard PICT files (use the suffix 
".pict") . If the host is a Windows machine then produce Bitmap files (use suffix 
".bmp"). This feature could be useful for easily documenting Lisa emulator screens. 

1 also recommend that the Lisa emulator support a keypress that calls this command. 
Or, if you want this file to be machine-neutral then store the screen in its own 
format, such as a simple bitmap. If you go this route I recommend that you use a 
tagged object file for the image file (this file could contain just 3 tags; a header 
tag, a footer tag, and a tag for the image data) . 

Example : PICT 

O PICTP / WRITE SCREEN PICTURE PERIODICALLY period 

Same as the PICT command but does not immediately produce a picture file . Instead, 
this command tells the debugger (or the emulator) to periodically produce a picture 
file based on the period parameter. Period represents the number of seconds that 
each picture should be taken. 

Example: PICTP 60 (periodically produce a picture every 60 seconds) 
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DISK BLOCK DUMPING 

O DMD / DUMP MOUNTED DISKS 

Displays a list of all the mounted emulator disk images . Each mounted disk is 
assigned a unique disk number which is used by the other disk block commands . The 
display shows the disk number and the disk size in 512 byte blocks . 

Example : DMD 

# SIZE 



800 

1 800 



o DDB / DUMP DISK BLOCK disk# { start-block# } {end-block#} 

Displays the contents of the specified 512 byte block range from the specified disk 
in a standard hex/ASCII format. If no blocks present then dumps all of the disk 
blocks. Also includes the block's 24 byte TAG (or 12 bytes if the full 24 are not 
available - the Macintosh can read Lisa disks but can only read 12 bytes of the 
TAG) . Use the DMD command to get the disk# . 

Example: DDB 1 200 300 (dumps blocks 200-300 from disk 1) 



SECTION 10 — IMPLEMENTATION LANGUAGE 



The implementation language should be a high-level language so that the emulator is 
as portable as possible . Potential language choices are C (or C++) or Pascal or any 
other high-level language that can handle the emulator ' s software needs . 

I recommend against using assembly language for the following reasons : 

o Assembly language is inherentaly non-portable between machines. 

o Assembly language is much harder to maintain. 

o Assembly language will most likely not provide any significant speed increases 
since today's machines with 300 MHz CPUs will be much faster than any emulator 
really needs no matter the language . 



SECTION 11 — IMPLEMENTATION MACHINE 



Any computer that supports the following hardware should be able to support an 
emulation of the Lisa: 

o Bit-mapped screen. Resolution must be at least 720h x 364v pixels. The 
machine can support color pixels but the Lisa supported only B/W display output . 

o Mouse . The Lisa supported only a single button mouse . Multi-button mice could 
be used by the Lisa emulator (you could use the emulation mouse so only 1 button 
acted as the Lisa's single-button or all buttons could work like the Lisa's mouse 
button) . 
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o At least 1 MB of memory (2MB was also supported) . Since the Lisa supported up 
to 1MB of RAM the emulator for simplicity sake should also support this . Additional 
memory would be needed by the emulator itself. If 1MB of RAM for the Lisa itself is 
not doable then you could always use a virtual-memory scheme (I bet that a VM scheme 
would not slow down an emulator given the speed of today's hard disks or even 
floppies) . 

o Keyboard with special keys . The Lisa keyboard contained an APPLE key and an 
OPTION key . The APPLE key was used for keyboard-based commands . The OPTION key was 
used to generate foreign or special characters. Today's Macintosh keyboards with 
the Apple (or Command) key and the Option key would work. Today's PC keyboards with 
the Control key and the Alt key would also work. 

o Fairly fast CPU and hard disk. The Lisa's CPU ran at 5 MHz and the 
peripherals were fairly slow. Therefore if you want an emulator to be at least as 
fast as the Lisa you should use a machine that is much faster than the Lisa. Any of 
today's machines such as Pentium-based Windows machines or 68020/30/40/PowerPC 
Macintosh machines should work well . You may actually have to slow down the 
emulator if it works too fast . 



SECTION 12 — FUN STUFF 



To make this emulator have some spirit I recommend that it also contain historical 
and technical information related to the Lisa. For example, there could be included 
in this emulator a history of the Lisa such as my Lisa Legacy paper. There could 
also be scanned Lisa documents such as Apple ' s Lisa Architecture paper and/or the 
Lisa designer interview from BYTE magazine . This information would provide the 
curious reader with some background information about the Lisa and its place in 
computer history. Displaying a picture of the Lisa during emulator startup would 
also be a nice touch (the Lisa image that originated with LisaDraw and which heads 
my Lisa paper could be a good candidate) . 

j SECTION 13 — REFERENCES ~ j 

The following references should prove valuable in understanding the Lisa hardware 
and software . The ability to read Pascal programming code is also needed since the 
Lisa's software was for the most part written in Lisa Pascal. You must also be able 
to at least read 68000 assembly language programming. 

The Architecture of the Lisa Personal Computer 

Apple Computer, 1984, 12 pages 

This is a great technical summary of the Lisa's hardware and software architecture 
which was written by one of the Lisa's designers. 

Lisa Product Data Sheets 

Apple Computer, 1983-1984 

These product sheets provide lots of concise information about the Lisa's hardware 
and software. Each sheet is around 4 pages long. I have the sheets for the Lisa 1 
hardware, Lisa 2 hardware, Lisa user tools (e.g. LisaDraw), Lisa programming tools 
(e.g. LisaPascal) , and peripherals (e.g. ImageWriter printer). 
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Lisa Owner's Guide 

Apple Computer, 1983-1984 

The Lisa 1 Owner's Guide and the Lisa 2 Owner's Guide are very useful since they 
provide detailed information about how the Lisa physically looked and how you 
performed basic tasks with it. If you're not familiar with the Lisa or don't have 
these manuals I highly recommend them. Also highly recommended are the Lisa tool 
manuals (e.g. LisaWrite) since these explain the details behind these tools. 

The Mac Bathroom Reader 
Owen Linzmayer, 1994 

For an extremely accurate and readable description of the Lisa's history see this 
book's chapter "Lisa: From Xerox with Love." If you read only a single history 
about the Lisa (or Apple Computer in general) make it this book. Owen is currently 
updating this book. Contact Owen for book availability info: 

e-mail: owenink@ix.netcom.com 

WWW: http: //www.netcom. com/~owenink/reviews .html/ 

Lisa Hardware Manual 
Apple Computer, 1981 and 1983 

This manual is the definitive description of the Lisa 1 computer's hardware. The 
1983 revision supersedes the 1981 manual and provides lots of information about the 
Lisa hardware interfaces which an emulator writer will definitely need. The 1981 
manual does describe a few items in a little more detail than this manual (e.g. the 
MMU info in the 1981 manual seems a little more complete) . The 1981 manual is 82 
pages long, the 1983 manual is 333 pages long. 

Lisa Boot ROM Listing 

Apple Computer 

This is the listing for the Lisa's boot ROM (version 2.48 "H") which was written in 
68000 assembly language. This is a must-have document for emulator writers since it 
shows how the boot ROM interfaces with the Lisa hardware to both test this hardware 
and to boot an OS from a disk device. If the hardware manual is unclear about a 
certain aspect of the hardware this listing will most likely have the answer. I 
have this listing as a disk file . 



As an example of the contents of the Boot ROM listing here ' s the mouse handling 
code. Note that the Boot ROM is in general very well commented. 



2F2A 
2F2A 
2F2A 
2F2A 
2F2A 
2F2A 
2F2A 
2F2A 
2F2A 
2F2A 
2F2A 
2F2A 
2F2A 
2F2A 
2F2A 
2F2A 
2F2A 



Hardware Interface for the Mouse 

Written by Rick Meyers 
(c) Apple Computer Incorporated, 1983 

The routines below provide an assembly language interface to the mouse . 
Input parameters are passed in registers, output parameters are returned 
in registers. Unless otherwise noted, all registers are preserved. 

The Mouse 

The mouse is a pointing device used to indicate screen locations . Mouse 
coordinates are located between pixels on the screen. Therefore, the 
X-coordinate can range from to 720, and the Y-coordinate from to 364. 
The initial mouse location is 0,0. 
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2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2A| 
2F2E| 
2F32| 
2F36| 
2F3A| 
2F3C| 
2F40| 
2F42| 
2F42| 
2F44| 
2F46| 
2F48| 
2F48| 
2F4A| 
2F4C| 
2F4E| 
2F4E| 
2FS0| 
2F54| 
2F56| 
2F56| 
2F58| 
2F5A| 
2F5C| 
2F5E| 
2F60| 



Mouse Scaling 

The relationship between physical mouse movements and logical mouse 
movements is not necessary a fixed linear mapping. Three alternatives 
are available: 1) unsealed, 2) scaled for fine movement and 3) scaled 
for coarse movement . 

When mouse movement is unsealed, a horizontal mouse movement of x units 
yields a change in the mouse X-coordinate of x pixels . Similiarly, a 
vertical movement of y units yields a change is the mouse Y-coordinate 
of y pixels . These rules apply independent of the speed of the mouse 
movement . 

When mouse movement is scaled, horizontal movements are magnified by 3/2 
relative to vertical movements . This is intended to compensate for the 
2/3 aspect ratio of pixels on the screen. When scaling is in effect, a 
distinction is made between fine (small) movements and coarse (large) 
movements . Fine movements are slightly reduced, while coarse movements 
are magnified. For scaled fine movements, a horizontal mouse movement of 
x units yields a change in the X-coordinate of x pixels, but a vertical 
movement of y units yields a change of (2/3) *y pixels. For scaled coarse 
movements, a horizontal movement a x units yields a change of (3/2) *x 
pixels, while a vertical movements of y units yields a change of y pixels. 

The distinction between fine movements and coarse movements is determined 
by the sum of the x and y movements each time the mouse location is 
updated. If this sum is at or below the 'threshold', the movement is 
considered to be a fine movement . Values of the threshold range from 
(which yields all coarse movements) to 256 (which yields all fine 
movements) . Given the default mouse updating frequency, a threshold of 
about 8 (threshold's initial setting) gives a comfortable transition between 
fine and coarse movements . 



48E7 7C00 
3038 0486 
3238 0488 
1438 048A 
4882 

1638 048B 
4883 

3802 
6C02 
4444 

3A03 
6C02 
4445 

D845 

9878 048E 
6E16 

D042 
3403 
D643 
D643 
D642 
5443 



Mouse Movement 

This routine is called by the GETINPUT routine when the COPS has 
reported mouse movement . All registers are preserved . 



Register Assignments : 

DO — Mouse X-Coordinate (integer) 

Dl — Mouse Y-Corrdinate (integer) 

D2 — Mouse Dx (integer) 

D3 — Mouse Dy (integer) 

MouseMovement 



@1 



MOVEM.L 


D1-D5, 


-<SP) 


; save registers 


MOVE.W 


MousX,D0 


; mouse X-coordinate 


MOVE.W 


MousY,Dl 


; mouse Y-coordinate 


MOVE.B 


MousDx 


D2 


; mouse Dx (byte) 


EXT.W 


D2 




; mouse Dx (integer) 


MOVE.B 


MousDy 


D3 


; mouse Dy (byte) 


EXT.W 


D3 




; mouse Dy (integer) 


MOVE.W 


D2,D4 




; mouse Dx 


BGE.S 


@1 




; branch if >= 


NEG.W 


D4 




; ABS (mouse Dx) 


MOVE.W 


D3,D5 




; mouse Dy 


BGE.S 


@2 




; branch if >= 


NEG.W 


D5 




; ABS (mouse Dy) 


ADD.W 


D5,D4 




; ABS(Dx) + ABS(Dy) 


SUB.W 


MousThresh, D4 


; - MouseThreshold 


BGT.S 


Coarse 




; branch if coarse movement 


ADD.W 


D2,D0 




; new X-coordinate (scale 1) 


MOVE.W 


D3,D2 




; save Dy 


ADD.W 


D3,D3 




; Dy*2 


ADD.W 


D3,D3 




; Dy*4 


ADD.W 


D2,D3 




; Dy*5 


ADDQ 


#2,D3 




; (Dy*5)+2 
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2F62 


6D02 




2F64 


5643 




2F66 


E643 




2F68 


D243 




2F6A 


6010 




2F6C 






2F6C 


D243 




2F6E 


3602 




2F70 


D443 




2F72 


D443 




2F74 


6D02 




2F76 


5242 




2F78 


E242 




2F7A 


D042 




2F7C 






2F7C 


4A40 




2F7E 


6C02 




2F80 


4240 




2F82 






2F82 


0C40 


02D0 


2F86 


6F04 




2F88 


303C 


02D0 


2F8C 






2F8C 


4A41 




2F8E 


6C02 




2F90 


4241 




2F92 






2F92 


0C41 


016C 


2F96 


6F04 




2F98 


323C 


016C 


2F9C 






2F9C 


31C0 


0486 


2FA0 


31C1 


0488 


2FA4 


31C0 


0496 


2FA8 


31C1 


0498 


2FAC 


4CDF 


003E 


2FB0 


4E75 




2FB2 






2FB2 






2FB2 






2FB2 






2FB2 






2FB2 






2FB2 






2FB2 






2FB2 


31FC 


0168 0486 


2FB8 


31FC 


00B6 0488 


2FBE 


31FC 


0008 048E 


2FC4 


707C 




2FC6 


6100 


D98E 


2FCA 


4E75 




2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 






2FCC 







@3 



Coarse 



@4 



@5 



@6 



@7 



BLT.S 


@3 


ADDQ 


#3,D3 


ASR.W 


#3,D3 


ADD.W 


D3,D1 


BRA.S 


Bounds 


ADD.W 


D3,D1 


MOVE.W 


D2,D3 


ADD.W 


D3,D2 


ADD.W 


D3,D2 


BLT.S 


@4 


ADDQ.W 


#1,D2 


ASR.W 


#1,D2 


ADD.W 


D2,D0 


TST.W 


DO 


BGE.S 


@5 


MOVE.W 


#0,D0 



CMP.W #MaxX,D0 

BLE.S @6 

MOVE.W #MaxX,D0 

TST.W Dl 

BGE.S @7 

MOVE . W #0 , Dl 

CMP.W #MaxY,Dl 

BLE.S @8 

MOVE.W #MaxY,Dl 

MOVE.W D0,MousX 

MOVE.W Dl,MousY 

MOVE.W D0,CrsrX 

MOVE.W Dl,CrsrY 

MOVEM.L (SP)+,D1-D5 
RTS 



branch if negative 
(Dy*5)+5 

Dy*(5/8) with rounding 
new Y-coordinate (scale 5/8) 
continue 

new Y-coordinate (scale 1) 
save Dx 
Dx*2 
Dx*3 

branch if negative 
(Dx*3)+1 

Dx*(3/2) with rounding 
new X-coordinate (scale 3/2) 

new X-coordinate >= 
branch if >= 
minimum X of 

new X-coordinate <= 720 
branch if <= 720 
maximum X of 720 

new Y-coordinate >= 
branch if >= 
minimum Y of 

new Y-coordinate <= 364 
branch if <= 364 
maximum Y of 364 

update Mouse X-coordinate 
update Mouse Y-coordinate 
also update cursor coordinates 

restore registers 
return 



Routine to initialize mouse handling 



MOVE 


.W 


#360,MousX 


MOVE 


.W 


#182,MousY 


MOVE 
MOVE 


.W 
Q 


#8 , MousThresh 
#$7C,D0 


BSR 




COPSCMD 


RTS 







set inital mouse location 

to center of screen 
set scaling threshold 
and enable mouse data 



Hardware Interface for the Cursor 

Written by Rick Meyers 
(c) Apple Computer Incorporated, 1983 



The routines below provide an assembly language interface to the cursor. 
Input parameters are passed in registers, output parameters are returned 
in registers. Unless otherwise noted, all registers are preserved. 

The Cursor 

The cursor is a small image that is displayed on the screen . It ' s shape 
is specified by two bitmaps, called 'data' and 'mask' . These bitmaps are 
16 bits wide and from to 32 bits high. The rule used to combine the 
bits already on the screen with the data and mask is 

screen <- (screen and (not mask)) xor data. 

The effect is that white areas of the screen are replaced with the cursor 
data . Black areas of the screen are replaced with (not mask) xor data . 
If the data and mask bitmaps are identical, the effect is to 'or' the data 
onto the screen. 
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2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FCC| 
2FD0| 
2FD4| 
2FDA| 
2FE0| 
2FE6| 
2FE8| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEA| 
2FEE| 
2FF2| 
2FF6| 
2FFA| 
2FFE| 
3000| 
3000| 
3002| 
3004| 
3008| 
3008| 
300C| 
300E| 
300E| 
300E| 
300E| 
300E| 
300E| 
300E| 
300E| 
300E| 
300E| 
300E| 
300E| 
300E| 
300E| 
300E| 
300E| 
300E| 



The cursor has both a location and a hotspot . The location is a position 
on the screen, with X-coordinates of to 720 and Y-coordinates of to 364 . 
The hotspot is a position within the cursor bitmaps, with X- and Y-coordi- 
nates ranging from to 16. The cursor is displayed on the screen with it's 
hotspot at location. If the cursor's location is near an edge of the screen, 
the cursor image may be partially or completely off the screen . 



Routine : Cursorlnit 
Arguments : None 

Function: Sets up the initial defaults used by the ROM cursor, 
position is set for center of the screen. 



Initial 



4278 0490 
4278 0492 
31FC 0010 0494 
31FC 0168 0496 
31FC 00B6 0498 
61CA 
4E75 



Cursorlnit 



MOVE.W 

MOVE.W 

MOVE.W 

MOVE.W 

MOVE.W 

BSR.S 

RTS 



#0,CrsrHotX 

#0,CrsrHotY 

#16,CrsrHeight 

#360,CrsrX 

#182,CrsrY 

Mouslnit 



cursor hotspot X-coordinate 
cursor hotspot Y-coordinate 
cursor hieght, 0—32 
initial cursor X-coordinate 
initial cursor Y-coordinate 
init mouse for cursor control 
return 



Cursor Hide and Display 

Care must be taken when updating the screen image which is ' under ' the 
cursor. The simplest approach is to remove the cursor from the screen 
(hide) , do the screen modification, then redisplay the cursor (display) . 
Each hide operation must be followed by a corresponding display 
operation. The operations are paired and can be nested. The first of a 
series of hides removes the cursor from the screen; it ' s corresponding 
display redisplays the cursor . Intervening operations have no apparent 
effect . 



Routine : CursorHide 

Arguments : None 

Function : Remove the cursor from the screen . Note that every call to 

CursorHide must be followed by exactly one call to CursorDisplay . 



48E7 COCO 
41F8 04A2 
2278 0528 
3038 0526 
323C 005A 
6004 

2298 
D2C1 
51C8 FFFA 

4CDF 0303 
4E75 



CursorHide 



(SP) 



@1 



MOVEM.L D0-D1/A0-A1,- 

LEA SavedData,A0 

MOVE . L SavedAddr , Al 

MOVE.W SavedRows,D0 

MOVE . W #MaxX/ 8 , Dl 

BRA.S @2 

MOVE.L (A0)+, (Al) 

ADD.W D1,A1 

DBF D0,@1 



MOVEM.L (SP)+,D0-D1/A0-A1 
RTS 



save registers 
saved data address 
saved data screen address 
rows of saved data 
bytes per row on screen 
test of rows=0 

from saved to screen 
screen address of next row 
loop ' SavedRows ' times 

restore registers 
return 



Routine : CursorDisplay 
Arguments : none 

Function: Redisplay the cursor. Note that every call to CursorDisplay 
must be preceeded by exactly one call to CursorHide . 



Register Assignments : 

DO — saved data X-coordinate, 

Dl — saved data Y-coordinate, 

D2 — left shift count 

D3 — 32-bit mask 

D4 — rows of saved data 

D5 — bytes per row on screen 



cursor data 
cursor mask 
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OE 
OE 
OE 
OE 
OE 
OE 
OE 


48E7 


FCFO 


12 


41F8 


04A2 


16 


2278 


0110 


1A 


45FA 


0900 


IE 


47FA 


08FC 


22 


3038 


0490 


26 


3238 


0492 


2A 
2E 


3838 


0494 


2E 
2E 


9078 


0496 


32 


4440 




34 


3400 




36 
3A 


0242 
4442 


OOOF 


3C 


0642 


0010 


40 


4283 




42 


4643 




44 


E5AB 




46 






46 
4A 
4C 
4C 
4E 
50 


0240 
6C0A 

4240 
E18B 
E18B 


FFFO 


52 


0642 


0010 


56 






56 
5A 


0C40 
6F14 


02B0 


5C 


0C40 


02D0 


60 


6602 




62 


7600 




64 






64 


303C 


02B0 


68 


E08B 




6A 


E08B 




6C 
70 


0642 


0010 


70 
70 


9278 


0498 


74 


4441 




76 
78 
78 
7A 
7C 
7E 
80 
82 


6C0C 

D841 
D241 
94C1 
96C1 
4241 
6010 




84 


3A3C 


016C 


88 


9A44 




8A 


B245 




8C 


6F0C 




8E 


383C 


016C 


92 


9841 




94 






94 


4A44 




96 


6C02 




98 


4244 




9A 






9A 


31C0 


0522 


9E 


31C1 


0524 


A2 
A6 
A6 


31C4 


0526 



AO — saved data address 

Al — saved data screen address 

A2 — cursor data address 

A3 — cursor mask address 



CursorDisplay MOVEM.L D0-D5/A0-A3, - (SP) 



811 



LEA 


SavedData, A0 


MOVE.L 


ScrnBase, Al 


LEA 


CrsrData, A2 


LEA 


CrsrMask,A3 


MOVE.W 


CrsrHotX,D0 


MOVE.W 


CrsrHotY,Dl 


MOVE.W 


Cr srHeight , D4 


bounds 


check the X-co 


SUB.W 


CrsrX,D0 


NEG.W 


DO 


MOVE.W 


D0,D2 


AND.W 


#$000F,D2 


NEG.W 


D2 


ADD.W 


#16, D2 


CLR.L 


D3 


NOT 


D3 


LSL.L 


D2,D3 


AND.W 


#$FFF0,D0 


BGE.S 


@0 



80 



01 



02 



MOVE . W #0 , DO 

LSL.L #8,D3 

LSL.L #8,D3 

ADD.W #16, D2 

CMP.W #MaxX-32,D0 

BLE . S @2 

CMP.W #MaxX,D0 

BNE.S @1 

MOVEQ #0 , D3 

MOVE . W #MaxX-32 , DO 

LSR.L #8,D3 

LSR.L #8,D3 

ADD.W #16, D2 



save registers 

saved data address 
screen memory address 
cursor data bitmap address 
cursor mask bitmap address 
cursor hotspot X-coordinate 
cursor hotspot Y-coordinate 
cursor height 



cursor X-coordinate 

- cursor hotspot X-coordinate 
upper left X-coordinate 
bit offset within word 

negated and converted to 

left shift count 
32-bit mask 
D3 = $0000FFFF 

shifted into position 

upper left X-coord rounded down 
branch if >= 

minimum upper left X-coord of 
adjust 32-bit mask 
adjust 32-bit mask 
adjust left shift count 

upper left X-coord <= 720-32 
branch if <= 720-32 

cursor off right edge ? 
branch if not off right edge 
mask off all bits 

maximum X-coord of 720-32 
adjust 32-bit mask 
adjust 32-bit mask 
adjust left shift count 



RM000 
RM000 



03 



04 



05 



Compute and bounds check the Y-coordinate of the data under the cursor . 



cursor Y-coordinate 

- cursor hotspot Y-coordinate 
branch if upper left Y >= 

decrease rows of saved data 
double for byte count 
increase cursor data address 
increase cursor mask address 
minimum upper left Y of 
continue 

maximum Y-coordinate 

- cursor height 

cursor bottom <= 364-CrsrHeight 
branch if <= 364-CrsrHeight 

last row on screen 
adjust rows of saved data 

rows of saved data >= ? 

branch if >= 

minimum rows of saved data 

saved data X-coordinate 
saved data Y-coordinate 
rows of saved data 



SUB.W 


CrsrY,Dl 


NEG.W 


Dl 


BGE.S 


@3 


ADD.W 


D1,D4 


ADD.W 


D1,D1 


SUB.W 


D1,A2 


SUB.W 


D1,A3 


MOVE.W 


#0,D1 


BRA.S 


@4 


MOVE.W 


#MaxY,D5 


SUB.W 


D4,D5 


CMP.W 


D5,D1 


BLE.S 


@5 


MOVE.W 


#MaxY,D4 


SUB.W 


D1,D4 


TST.W 


D4 


BGE.S 


@5 


MOVE.W 


#0,D4 


MOVE.W 


DO , SavedX 


MOVE.W 


Dl,SavedY 


MOVE.W 


D4 , SavedRows 



Display the cursor on the screen . 
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I E648 




I D2C0 




| 7A5A 




| C2C5 




| D3C1 




I 21C9 


0528 


I 6016 




I 301A 




I E5B8 




I C083 




I 321B 




I E5B9 




I C283 




I 4681 




I 20D1 




1 C391 




I B191 




| D2C5 




I 51CC 


FFE8 


| 4CDF 


0F3F 


| 4E75 





@6 



@7 



LSR 


W 


#3, DO 


convert X-coord to bytes 


ADD 


W 


D0,A1 


and add to screen address 


MOV1 


:q 


#MaxX/8,D5 


bytes per row on screen 


MULI 


J 


D5,D1 


* Y-coord 


ADD 


L 


D1,A1 


added to screen address 


MOV1 


:.l 


Al , SavedAddr 


saved data screen address 


BRA 


s 


@7 


test for rows=0 


MOV1 


I.W 


(A2)+,D0 


cursor data 


ROL 


L 


D2,D0 


shift to proper bit position 


AND 


L 


D3,D0 


eliminate unwanted bits 


MOVI 


I.W 


(A3)+,D1 


cursor mask 


ROL 


L 


D2,D1 


shift to proper bit position 


AND 


L 


D3,D1 


eliminate unwanted bits 


NOT 


L 


Dl 


invert cursor mask 


MOVI 


:.l 


(Al), (A0) + 


from screen to saved data 


AND 


L 


Dl, (Al) 


screen and (not mask) 


EOR 


L 


DO, (Al) 


xor cursor data 


ADD 


W 


D5,A1 


screen address of next row 


DBF 




D4,@6 


loop ' SavedRows ' times 


MOVI 


ZM.L 


(SP)+,D0-D5/A0-A3 


restore registers 


RTS 






return 



Lisa Schematics 

Apple Computer, 1983-1984, 25 pages 

These schematics can be useful if the hardware manual is unclear about how Lisa 
subsystems are designed and how they communicate . 

SYSTEM. LLD Disassembly 

David T. Craig, 1987-1988, 63 pages 

This document (which consists of 2 documents) provides lots of information about the 
Lisa memory-mapped I/O memory locations. It describes the low-level drivers (LLD) 
which the Lisa OS and its drivers call when they want to interface with the Lisa 
hardware. This interface controls the mouse, screen location, screen contrast, 
speaker, keyboard, alarms, clock, disk drives. 

Lisa Workshop development manuals 

Apple Computer 

This series of 3 manuals describes in detail how to write programs for the Lisa. 
Though much of this information will not help the emulator writer this series does 
provide lots of great background information on how the Lisa works . The 3 manuals 
in this series are: 

o Lisa Language (453 pages) 

o Lisa Workshop User's Guide (399 pages) 
o Lisa System Software (352 pages) 

The Lisa Language manual (which describes the Pascal language) contains in 
description of the Lisa hardware library in Appendix F which any emulator writer 
would need to know very well . The interface for this library follows : 
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type 



Pixels 


= Integer; 




ManyPixels 


= Longlnt; 




CursorHeight 


= Integer; 




CursorPtr 


= A Integer, 




DateArray 


= Record 






year 


Integer; 




day 


Integer; 




hour 


Integer; 




minute 


Integer; 




second 


Integer; 




end; 




Frames 


= Longlnt; 




Seconds 


= Longlnt; 




Milliseconds 


= Longlnt; 




Microseconds 


= Longlnt; 




SpeakerVolume 


= Integer; 




ScreenContrast 


= Integer; 




KeybdQIndex 


= 1. .1000; 




Keybdld 


= Integer; 




KeyCap 


= 0. .127; 




KeyCapSet 


= Set of KeyCap; 


KeyEvent 


= Packed Record 




key 


KeyCap; 




ascii 


Char; 




state 


Integer; 




mouseX 


Pixels; 




mouseY 


Pixels; 




time 


Milliseconds ; 




end; 




{ Mouse } 







Procedure MouseLocation (var x: Pixels; var y: Pixels) ; 
Procedure MouseUpdates (delay: Milliseconds) ; 
Procedure MouseScaling (scale: Boolean); 
Procedure MouseThresh (threshold: Pixels) ; 
Function MouseOdometer : ManyPixels; 

{ Cursor } 

Procedure CursorLocation (x: Pixels; y: Pixels) ; 
Procedure CursorTracking (track: Boolean); 

Procedure Cursorlmage (hotX: Pixels; hotY: Pixels; height: CursorHeight; 

data: CursorPtr; mask: CursorPtr); 

Procedure Busylmage (hotX: Pixels; hotY: Pixels; height: CursorHeight; 

data: CursorPtr; mask: CursorPtr); 
Procedure BusyDelay (delay: Milliseconds) ; 

{ Screen } 

Function FrameCounter : Frames; 

Procedure ScreenSize (var x: Pixels; var y: Pixels) ; 

Function Contrast: ScreenContrast; 
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Procedure SetContrast (contrast: ScreenContrast) ; 

Procedure RampContrast (contrast: ScreenContrast); 

Function DimContrast : ScreenContrast; 

Procedure SetDimContrast (contrast: ScreenContrast); 

Function FadeDelay: Milliseconds; 

Procedure SetFadeDelay (delay: Milliseconds) ; 

{ Speaker } 

Function Volume: SpeakerVolume ; 

Procedure SetVolume (volume: SpeakerVolume); 

Procedure Noise (waveLength: Microseconds) ; 

Procedure Silence; 

Procedure Beep (waveLength: Microseconds; duration: Milliseconds); 

{ Keyboard } 

Function Keyboard: Keybdld; 

Function Legends : Keybdld; 

Procedure SetLegends (id: Keybdld) ; 

Function KeylsDown (key: KeyCap) : Boolean; 

Procedure KeyMap (var keys: KeyCapSet) ; 

Function KeybdPeek (repeats: Boolean; index: KeybdQIndex; 

var event : KeyEvent ) : 

Boolean; 
Function KeybdEvent (repeats: Boolean; wait: Boolean; var event: KeyEvent): 

Boolean; 
Procedure RepeatRate (var initial: Milliseconds; 

var subsequent: Milliseconds); 
Procedure SetRepeatRate (initial: Milliseconds; subsequent: Milliseconds); 

{ Timers } 

Function MicroTimer: Microseconds; 
Function Timer: Milliseconds; 

{ Date and Time } 

Procedure DateTime (var date: DateArray) ; 

Procedure SetDateTime (date: DateArray); 

Procedure DateToTime (date: DateArray; var time: Seconds); 

{ Time Stamp } 

Function TimeStamp: Seconds; 

Procedure SetTimeStamp (time: Seconds); 

Procedure TimeToDate (time: Seconds; var date: DateArray); 

The Lisa Workshop User's Guide contains a section (chapter 8) on LisaBug, the Lisa's 
low-level 68000-oriented debugger. This volume also describes all of the Workshop's 
utility programs (e.g. the 68000 code file disassembler). 
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Lisa Chip Data Sheets 
40 pages or so 

These are the technical data sheets which chip manufactures created. I have the 
data sheets for the VIA, COPS, and the AM9512 math chip (a socket for this is 
available on Lisa 1 machines, but the Lisa software never really supported this chip 
to my knowledge so I recommend that this chip not be supported by the emulator) . 
These specs are needed so you will understand the gory details behind these chips . 

ImageWriter Printer Reference Manual 

Apple, 1984 

This was the printer that many Lisa user's used. This printer supported 3 modes of 
printing: draft (used the printer's built-in character sets, ugly but fast), 
standard (72 dpi bitmapped output, ok looking, somewhat slow) , and high quality (144 
dpi, used for most printing needs, very good looking, slow) . For a successful 
emulator I recommend that this printer's output be emulated. To do this you would 
need to write a "driver" for this printer within the emulator that emulated all of 
the printer ' s control codes . The output of this driver should be a file which the 
host computer could print . I recommend that the output of this driver be a generic 
file containing a set of bitmapped pages at 72 or 144 dpi. A separate program 
residing on the host computer would then look for these files and print them to the 
host machine's printer. This strategy removes printing details from the emulator 
and assigns it to another program which can be modified by itself without effecting 
the emulator. 

David Craig also has several printouts from the ImageWriter for the Lisa showing 
what the Lisa could do. David also has a complete listing of all of this printer's 
native built-in character sets which an emulator may want to support for Lisa draft 
printing. 

68000 Assembly Language Programming 
Kane, Hawkins, Leventhal, 1981 

This is a great 68000 book. I recommend this book and Motorola's original 68000 
book (it has a blue cover) . 

Microcomputer Architecture and Programming : The 68000 Family 
John F. Wakerly, 1989 

This is a good book that compliments Leventhal ' s 68000 book. Includes some fairly 
detailed information about 68000 emulation using the Pascal language (see page 
155+) . 

MacWorks Plus: Making a Lisa Speak Macintosh 
Charles Lukaszewski, Sun Remarketing, 1989, 4 pages 

This article describes how the Macintosh emulator that ran on a Lisa was created. 
It provides some good information about the low-level disk booting aspects of the 
Lisa's boot ROM. 
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The Legacy of the Apple Lisa Personal Computer: An Outsider's View 

David T. Craig, 1993, 19 pages 

This paper attempts to describe the key aspects of the Lisa's operation and 
architecture . It contains several pictures of the Lisa including a sample Lisa 
screen showing its GUI interface. It also contains an extensive reference section 
listing the majority of the 300+ Lisa documents I have and which others may want to 
read. These include the Lisa Product Introduction Plan (PIP) and the Lisa Marketing 
Requirements Document (MRD) . 

That's all folks! 
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